package io.youngledo.usb.storage;

import io.youngledo.usb.task.ProgressTracker;
import java.io.File;
import java.io.InputStream;
import java.util.List;

/// **通用对象存储服务接口**
///
/// 定义了所有对象存储服务需要实现的基本操作
///
public interface ObjectStorageService extends AutoCloseable {

    /// **连接到存储服务**
    ///
    /// **参数:**
    /// - `config` - 存储配置
    ///
    void connect(StorageConfig config);

    /// **测试连接是否有效**
    ///
    /// **返回值:** `true` 如果连接有效
    ///
    boolean isConnected();

    /// **断开连接**
    ///
    void disconnect();

    /// **列出所有存储桶**
    ///
    /// **返回值:** 存储桶列表
    ///
    /// **异常:** 操作失败时抛出 `io.youngledo.usb.exception.UniversalStorageException` 运行时异常
    ///
    List<StorageBucket> listBuckets();

    /// **创建存储桶**
    ///
    /// **参数:**
    /// - `bucketName` - 存储桶名称
    ///
    /// **异常:** 操作失败时抛出 `io.youngledo.usb.exception.UniversalStorageException` 运行时异常
    ///
    void createBucket(String bucketName);

    /// **删除存储桶**
    ///
    /// **参数:**
    /// - `bucketName` - 存储桶名称
    ///
    /// **异常:** 操作失败时抛出 `io.youngledo.usb.exception.UniversalStorageException` 运行时异常
    ///
    void deleteBucket(String bucketName);

    /// **列出存储桶中的对象**
    ///
    /// **参数:**
    /// - `bucketName` - 存储桶名称
    /// - `prefix` - 前缀过滤器（可为null）
    /// - `recursive` - 是否递归列出子目录
    ///
    /// **返回值:** 对象列表
    ///
    /// **异常:** 操作失败时抛出 `io.youngledo.usb.exception.UniversalStorageException` 运行时异常
    ///
    List<StorageObject> listObjects(String bucketName, String prefix, boolean recursive);

    /// **上传文件**
    ///
    /// **参数:**
    /// - `bucketName` - 存储桶名称
    /// - `objectKey` - 对象键（完整路径）
    /// - `file` - 要上传的文件
    ///
    /// **异常:** 操作失败时抛出 `io.youngledo.usb.exception.UniversalStorageException` 运行时异常
    ///
    void uploadFile(String bucketName, String objectKey, File file);

    /// **上传文件流**
    ///
    /// **参数:**
    /// - `bucketName` - 存储桶名称
    /// - `objectKey` - 对象键（完整路径）
    /// - `inputStream` - 输入流
    /// - `contentLength` - 内容长度
    ///
    /// **异常:** 操作失败时抛出 `io.youngledo.usb.exception.UniversalStorageException` 运行时异常
    ///
    void uploadFile(String bucketName, String objectKey, InputStream inputStream, long contentLength);

    /// **上传文件（带进度跟踪）**
    ///
    /// **参数:**
    /// - `bucketName` - 存储桶名称
    /// - `objectKey` - 对象键（完整路径）
    /// - `file` - 要上传的文件
    /// - `progressTracker` - 进度跟踪器
    ///
    /// **异常:** 操作失败时抛出 `io.youngledo.usb.exception.UniversalStorageException` 运行时异常
    ///
    default void uploadFileWithProgress(String bucketName, String objectKey, File file, ProgressTracker progressTracker) {
        uploadFile(bucketName, objectKey, file);
    }

    /// **上传文件流（带进度跟踪）**
    ///
    /// **参数:**
    /// - `bucketName` - 存储桶名称
    /// - `objectKey` - 对象键（完整路径）
    /// - `inputStream` - 输入流
    /// - `contentLength` - 内容长度
    /// - `progressTracker` - 进度跟踪器
    ///
    /// **异常:** 操作失败时抛出 `io.youngledo.usb.exception.UniversalStorageException` 运行时异常
    ///
    default void uploadFileWithProgress(String bucketName, String objectKey, InputStream inputStream, long contentLength, ProgressTracker progressTracker) {
        uploadFile(bucketName, objectKey, inputStream, contentLength);
    }

    /// **下载文件**
    ///
    /// **参数:**
    /// - `bucketName` - 存储桶名称
    /// - `objectKey` - 对象键（完整路径）
    ///
    /// **返回值:** 文件输入流
    ///
    /// **异常:** 操作失败时抛出 `io.youngledo.usb.exception.UniversalStorageException` 运行时异常
    ///
    InputStream downloadFile(String bucketName, String objectKey);

    /// **下载文件到本地**
    ///
    /// **参数:**
    /// - `bucketName` - 存储桶名称
    /// - `objectKey` - 对象键（完整路径）
    /// - `localFile` - 本地文件路径
    ///
    /// **异常:** 操作失败时抛出 `io.youngledo.usb.exception.UniversalStorageException` 运行时异常
    ///
    void downloadFile(String bucketName, String objectKey, File localFile);

    /// **下载文件到本地（带进度跟踪）**
    ///
    /// **参数:**
    /// - `bucketName` - 存储桶名称
    /// - `objectKey` - 对象键（完整路径）
    /// - `localFile` - 本地文件路径
    /// - `progressTracker` - 进度跟踪器
    ///
    /// **异常:** 操作失败时抛出 `io.youngledo.usb.exception.UniversalStorageException` 运行时异常
    ///
    default void downloadFileWithProgress(String bucketName, String objectKey, File localFile, ProgressTracker progressTracker) {
        downloadFile(bucketName, objectKey, localFile);
    }

    /// **删除对象**
    ///
    /// **参数:**
    /// - `bucketName` - 存储桶名称
    /// - `objectKey` - 对象键（完整路径）
    ///
    /// **异常:** 操作失败时抛出 `io.youngledo.usb.exception.UniversalStorageException` 运行时异常
    ///
    void deleteObject(String bucketName, String objectKey);

    /// **批量删除对象**
    ///
    /// **参数:**
    /// - `bucketName` - 存储桶名称
    /// - `objectKeys` - 对象键列表
    ///
    /// **异常:** 操作失败时抛出 `io.youngledo.usb.exception.UniversalStorageException` 运行时异常
    ///
    void deleteObjects(String bucketName, List<String> objectKeys);

    /// **创建文件夹（通过创建以/结尾的空对象实现）**
    ///
    /// **参数:**
    /// - `bucketName` - 存储桶名称
    /// - `folderKey` - 文件夹键（应以/结尾）
    ///
    /// **异常:** 操作失败时抛出 `io.youngledo.usb.exception.UniversalStorageException` 运行时异常
    ///
    void createFolder(String bucketName, String folderKey);

    /// **获取对象元数据**
    ///
    /// **参数:**
    /// - `bucketName` - 存储桶名称
    /// - `objectKey` - 对象键
    ///
    /// **返回值:** 对象信息
    ///
    /// **异常:** 操作失败时抛出 `io.youngledo.usb.exception.UniversalStorageException` 运行时异常
    ///
    StorageObject getObjectInfo(String bucketName, String objectKey);

    /// **获取存储服务类型**
    ///
    /// **返回值:** 存储类型
    ///
    StorageType getStorageType();

    /// **获取当前配置**
    ///
    /// **返回值:** 存储配置
    ///
    StorageConfig getConfig();

    /// **生成预签名URL（如果支持）**
    ///
    /// **参数:**
    /// - `bucketName` - 存储桶名称
    /// - `objectKey` - 对象键
    /// - `expiry` - 过期时间（秒）
    ///
    /// **返回值:** 预签名URL，如果不支持则返回null
    ///
    /// **异常:** 操作失败时抛出 `io.youngledo.usb.exception.UniversalStorageException` 运行时异常
    ///
    default String generatePresignedUrl(String bucketName, String objectKey, int expiry) {
        return null; // 默认不支持
    }
}